Internet Info 1993

home *** CD-ROM | disk | FTP | other *** search

/ Internet Info 1993 / Internet Info CD-ROM (Walnut Creek) (1993).iso / networking / terms / kermit / d / hdps8.doc < prev next >

Wrap

Text File | 1988-08-16 | 32.5 KB | 925 lines

Honeywell GCOS Kermit Version 1.1 January 1985 This writeup describes the features and use of Kermit-GCOS, a program for Kermit protocol file transfers. Kermit-GCOS runs under the Honeywell GCOS time sharing system (TSS) and should normally be in- stalled on the TSS command library as file CMDLIB/KERM to run as the TSS command KERMIT. It can, however, be placed on any user catalog and run as a TSS user program. Kermit-GCOS was written by John Huxtable, University of Kansas Academic Computing Services. On first reading, you may want to skip many of the sections which provide detailed information and look at only the overview and example sections. Before using Kermit-GCOS, however, you should go back and read the full writeup. 1.1.1. What is Kermit?______________________ Kermit is a protocol designed for reliable file transfer between computers. The transfer takes place through a standard RS-232 com- munications port, allowing implementation of Kermit transfer programs on most computers. Although Kermit is technically the name of the transfer protocol, it is common practice to refer to both the protocol and programs which use the protocol as Kermits; this will be done through the remainder of this writeup. Kermit development started at the Columbia University Center for Computing Activities in 1981. The primary developers were Bill Catchings and Frank da Cruz. Since that time the protocol has been ex- tended and implemented for many systems. Persons interested in how the protocol works should read articles in the June and July 1984 issues of Byte____ magazine which describe it in some detail. In order to transfer a file with Kermit, Kermit must be running on both the sending and receiving computers. One Kermit (called "local Kermit") must be able to establish the connection with the other Kermit (called "remote Kermit"). In the case of transfer between a microcom- puter and a mainframe this is generally done by the microcomputer Kermit acting as a terminal as well as providing file transfer capability. Microcomputer versions of Kermit are available from many bulletin board systems. A tape containing all "known" versions of Kermit can be obtained from Columbia University. For current ordering information contact: KERMIT Distribution Columbia University Center for Computing Activities 7th Floor, Watson Laboratory 612 West 115th Street New York, N.Y. 10025 - 1 - 1.1.2. Syntax Conventions_________________________ To show the syntax of commands and responses this writeup uses the following conventions: Angle brackets surround a description of what should be typed. For example, <option> means to type a Kermit option; it does not___ mean type "<option>" literally. Square brackets surround an optional item. For example, Kermit [<command>] means type "Kermit", optionally followed by some command. If a "*" fol- lows the closing square bracket, it means "zero or more". For example, Kermit [<option>]* means type "Kermit" followed by zero or more options. Control sequences are shown using the convention that "^x" means "hold the control key down, press the 'x' key, then release both keys." For example, when asked to type ^] hold the control key down and push the ] key. When a keyword appears in a syntax description, the letters which appear in uppercase must be typed. The letters which appear in lower case are optional. Digits and special characters must be typed. For example: +OverWrite indicates that "+", "O" and "W" MUST be typed; the letters "ver" and "rite" are optional. The minimum entry to invoke this option would be: +ow Note that the characters may be entered in either case; the case in the syntax description is merely a method to indicate which characters are required. 1.1.3. GCOS File Formats________________________ GCOS uses many different methods of storing and accessing files. Since other systems do not necessarily support analogs of GCOS formats, three file formats have been defined to handle all cases. - 2 - The default format is "Text". This is the standard format used for text files in GCOS TSS. When Kermit-GCOS transmits a text file, it removes GCOS file control and record control words from the file and transmits a carriage-return, line-feed sequence at the end of each record. It also deletes the high (9th) bit of each nine-bit byte. These bits are always zero in a text file so no information is lost. When Kermit-GCOS receives a file in text format, it adds a zero high (9th) bit to each byte so that four fit evenly into each 36-bit Honey- well word. It also converts the carriage-return, line-feed sequence at the end of each record into Honeywell record control information and stores the file in GCOS system standard TSS format. Files transmitted to GCOS can always be stored in text format even if the file content is eight-bit data, such as a .COM or .EXE file from a microcomputer. When transferred from GCOS to a system of the originating type, such files will be restored exactly to their original form. Text is the most con- venient format to use for files transferred to GCOS for archival pur- poses. The second format is "BYtestream". A bytestream file is the best format to use when sending non-text (binary) files, such as eight-bit telemetry data, from other systems to GCOS for processing on GCOS. The data is stored with no record structure, i.e. only the bytes received with no added "control" information. As in text mode, Kermit-GCOS adds a high-order zero bit to each incoming eight-bit character, to align on nine-bit Honeywell byte boundaries with four characters per 36-bit word. The unused portion of the last 1280-byte block of the file is filled with zeros (ASCII nulls). When transmitting a bytestream file, Kermit- GCOS strips the high-order bit from each 9-bit byte, and transmits the full file including any trailing zeros (nulls) which pad the last block. The Bytestream option automatically sets the +Random option since bytestream files must be accessed in random (direct access) mode. The third format is "BItstream". A bitstream file also contains data only, with no control information. It is different from bytestream in that each nine eight-bit bytes received are packed into two 36-bit Honeywell words. During transmission, each pair of Honeywell words is unpacked into nine eight-bit bytes. This format permits transmitting and receiving GCOS files, such as random libraries, which use all 36 bits in each word. Bitstream format is useful for archiving binary GCOS files on other systems. One of the other two formats should be used for most other purposes. Bitstream files should be accessed in random (direct access) mode. Specifying Bitstream format automatically implies the +Random option. 1.1.4. GCOS Data Transfer Modes_________________ Kermit-GCOS can operate in two communications modes. One mode receives packets as standard ASCII input, with a carriage return (decimal 13) used to end each packet; the other receives packets using "paper-tape" mode, with an ASCII DC3 character (also known as XOFF, ^S, decimal 19, or hexadecimal 13) used to end each packet. Which mode you should use depends on your GCOS site's system configuration. - 3 - Between your local Kermit and Kermit-GCOS is a Honeywell communica- tions computer, called a front-end processor. One of the Honeywell front-end software programs is called GRTS. GRTS uses the at-sign (@) as a character delete code for normal input and provides no way to change this. For example, the character sequence "ABC@@D" would be received through GRTS as "AD". Since the Kermit protocol requires that all printable ASCII characters (including @) can be sent and received, by default Kermit-GCOS uses paper-tape mode to read packets. In paper- tape mode, "@" is treated as a normal printing character. In this mode, however, the end of input is indicated by an ASCII DC3 character (XOFF) instead of a carriage return. This means that before beginning a file transfer you must set the send end of line character for your local Ker- mit to this value. Honeywell's newer front end software has the ability to change the character delete code. If you change it to a non-printing ASCII character (e.g. backspace or delete) then you need not use paper-tape mode. For non-paper-tape input mode, your local send end of line character should be a carriage return. This is the default for most versions of Kermit. To select this mode for Kermit-GCOS use the -TapeMode option which is described in the option section below. Unless you must operate in paper-tape mode, it is best to use the -TapeMode option. Tape mode prohibits the use of XON/XOFF flow control, since the XOFF control would also signal the end of a packet. In general, GRTS does not support flow control; however, if your site has implemented flow control for GRTS, sending a Kermit packet while Kermit- GCOS is not in a receive state would lock the line. You would then have to escape to interactive mode, type ^Q^D^S to regain control, and restart the file transfer from the beginning. Flow control can also be a problem if your connection to GCOS is through a network. To use tape mode through a network it must not depend on XON/XOFF control for blocks the size of Kermit packets (up to 96 characters). You may need to set network parameters to pass XOFF as data. Consult with local support staff or see local documentation if your connection is through a network. Finally, whenever GRTS is ready for input it sends an ASCII DC1 character. If your local Kermit has an option for DC1 (^Q or XON) hand- shaking, you should select it, especially if you are using tape mode. 1.2.1. An Overview of Kermit-GCOS______________ This section presents a summary of the features of Kermit-GCOS. It assumes you are already familiar with some basic information about GCOS time-sharing, such as how to log on and off. If you are not, then first read appropriate documentation for these topics. Kermit-GCOS operates as a remote version only. That is, it never originates a connection. It must be called by Kermit running on another system, usually a microcomputer Kermit in local mode acting as a ter- minal. - 4 - Commands and options to control Kermit-GCOS can be supplied on the command line, entered following prompts in interactive mode, or sent from your local Kermit through the use of the Kermit-GCOS server mode. Multiple files can be transmitted by supplying a list of names through the index file option. Separate file format options can be given for each entry in the index file. A working directory can be defined as the default location for files to be sent or received. The working directory is internal to Kermit-GCOS. It is not dependent on the working directory facility in- troduced recently in GCOS. 1.2.2. Invoking Kermit-GCOS_______________ To start Kermit-GCOS, enter the following command line: KERMit [<kermit command>] [<option>]* where the "<kermit command>" is an optional Kermit command. If you do not specify a command, Kermit will enter interactive mode, prompting you for commands. If you do specify a command, Kermit will execute the com- mand and then end. If options are given but no command, Kermit sets the options and enters interactive mode (see Kermit Options, below). 1.2.3. Kermit Commands______________________ Kermit-GCOS recognizes the following commands: ? -- Print a List of Commands Recognized Typing a "?" as a command will cause a list of recognized com- mands to be printed. Done -- Exit Kermit Done The Done command exits Kermit. You may also type "Exit" or "Quit". Help -- Provide Basic Explanations Help <command> Help <option> The Help command prints information about the <command> or <option> specified. Specifically, the relevant portion of this document is printed. Receive -- Receive a file Receive [<option>]* The Receive command causes Kermit-GCOS to wait for files to be sent from the local Kermit. The files will be created or ac- - 5 - cessed according to the current option settings, unless overrid- den on the command line (see Kermit Options, below). SENd -- Send a File SENd [<filespec>]* [<option>]* A <filespec> is either the name of a file to send or "in- deX=filename" where the file contains Kermit SENd command options and filespecs. The SENd command causes Kermit-GCOS to send files to the local Kermit. The files will be sent according to the current option settings, unless overridden on the command line or in an index file. Kermit-GCOS will wait for the number of seconds specified in the Delay option before starting to send the files. This allows you time to escape back to your local Kermit and type RECEIVE. SERver -- Enter Server Mode SERver [<option>]* The SERver command causes Kermit-GCOS to enter server mode. While in server mode, Kermit-GCOS will wait for commands from your local Kermit. When a command is received, it is executed. Server mode is the preferred mode of operation, although not all local Kermits support it. If your local Kermit supports server mode, you should use it. The use of server mode is detailed more fully below. SET -- Set Kermit Options SET [<option>]* The SET command causes Kermit to set its options as you specify on the command line. Normally, options given on a command line apply only to that command. A SET command causes them to change until a later SET command is given. STatus -- Print Options Status STatus The STatus command causes Kermit-GCOS to print a list of the cur- rent option settings. 1.2.4. Kermit Options_____________________ The following options are recognized (default settings are shown in parentheses): ? CWD=pathname DeBug=function (Off) Delay=nn (10) (+|-)Discard (-) - 6 - Format=fileformat (Text) indeX=filename (+|-)OverWrite (-) (+|-)Permanent (+) (+|-)Random (-) SendEndOfLine=nn (13) SendStartofPacket=nn (1) (+|-)TapeMode (+) Options: ? causes a list of the allowed options for the command given to be printed. CWD=pathname sets the Kermit working directory to the specified path. By default, your working directory is your USERID. It can be changed to any catalog or subcatalog where you want files placed by default. DeBug=function specifies how much debugging information is to be written to the debug file "kerm*dbg". The default is "Off", which means that no debugging information will be written. "States" causes the cur- rent protocol state to be written when it changes. "Packets" causes each packet sent or received to be written. "All" causes all possible debug information to be written. This information is rarely useful, unless you suspect that your communications line is noisy and wish to inspect what is being sent. Delay=nn causes Kermit to wait nn seconds before sending the first packet when using the SENd command. The default is 10 seconds. +Discard causes Kermit to discard an incomplete transmission. If you in- terrupt the transmission of a file, the file will not be created on GCOS. If -OverWrite is in effect, the previous contents will be unchanged. Format=fileformat causes any file transferred in either direction to be treated ac- cording to the file format specified. The formats are "Text", "BYtestream", and "BItstream". See the section on file formats. The default is Text. indeX=filename specifies a file containing Kermit SENd commands and options, one command per line. This option permits sending multiple files with a single command. This option is analgous to the "wildcard send" feature of some Kermits in that it allows transfering mul- tiple files easily. It was selected for Kermit-GCOS because GCOS does not support wildcard names, and allowing an index file of names provides additional flexiblity in sending dissimilar names. This option is only meaningful when used with the Kermit SENd command, or from "GET" commands received in Server Mode. Only the "Format=", +Random, +Discard, -Permanent and +OverWrite op- tions may be used in index files. - 7 - +OverWrite causes an existing file of the same name to be overwritten. The default is -OverWrite, which causes the incoming file to be renamed to avoid conflicts. The file is renamed by appending "_n" to the file, where n is the smallest digit not resulting in a clash. If the filename is too long, the underscore will be omitted. If the filename is still too long, characters will be deleted from the end until it fits. -Permanent causes Kermit to use standard GCOS rules for creating/accessing files. So if there are no slashes or dollar signs in the filename and if the filename is less than or equal to eight characters long, and if a quick access file of the same name does not already exist, the file will be created as temporary. Other- wise it will be created as permanent. If +Permanent (the default) is used, the file will always be created/accessed as permanent. +Random causes Kermit to access the file as random. The default is se- quential, or -Random. For non-text files, +Random must be specified. SendEndOfLine=nn causes Kermit to terminate its outgoing packets with the ASCII character whose decimal value is nn. Example: SendEndOfLine=26 would cause Kermit to terminate its outgoing packets with a ^Z (decimal ASCII value = 26). The default is carriage return (value = 13). SendStartofPacket=nn causes Kermit to start its outgoing packets with the ASCII character whose decimal value is nn. Example: SendStartof- Packet=26 would cause Kermit to start its outgoing packets with a ^Z (decimal ASCII value = 26). The default is ^A (value = 1). -TapeMode causes Kermit to use standard GCOS terminal input mode instead of "paper tape" input mode to read incoming packets. See the GCOS Data Transfer Modes section, above, for more information. The default, +tapemode, must be used at sites where the character delete code is "@" because Kermit requires the ability to send and receive all printable ASCII characters. 1.2.5. Server Mode__________________ Kermit-GCOS server mode enables Kermit-GCOS to receive commands through packets from your local Kermit if it supports server mode. This eliminates the need to switch back and forth between terminal mode and local mode each time you start a file transfer. In addition to the file transfer commands, GET and SEND, Kermit- GCOS Server mode supports several generic commands defined in the Kermit protocol. A short list of the commands as given in the Kermit Protocol manual follows. Be warned that not all Kermits support all Server com- mands, and even if a Kermit does support a command, it may not be in- voked with the same name as another Kermit's. For example, the "erase" - 8 - command, which releases files, is called the "remote delete" command by Kermit-MS. Read the documentation for your microcomputer Kermit for details. The following server commands are supported: CWD - Change Working Directory Erase - Release a file Finish - Terminate Server Mode Get - Receive a file from GCOS Logout - Terminate Kermit and Disconnect from TSS Send - Send a file to GCOS Status - Query Kermit-GCOS Status Type - List a file. The following descriptions of server mode commands apply to Kermit-MS. Bye This command ends your GCOS session for you and in addition, exits Kermit. You will then be back in MS-DOS. CWD This command is used to change your working directory (catalog). By default, your working directory is your userid, so any files that you send will be created under your userid but not under any catalog. Suppose you wanted to send your files to a subcatalog on your account called "/microfiles". You would enter REMote CWD /microfiles in Kermit-MS, enter a RETURN to the "Password:" prompt, and then use the "send" command. Any files sent would be placed under the "/microfiles" catalog. Typing "REMote CWD" with no catalog specified causes your current working catalog to be displayed. Erase Erase is used to delete a file from your GCOS current working directory. You must enter REMote DELete <filename> to invoke this command. Erasing multiple files with one command is not supported. Finish This command tells Kermit-GCOS to exit server mode. This is use- ful if you want to resume using Kermit-MS as a terminal after doing some file transfers. Just enter "Finish", then "connect", then enter a RETURN and you will be back at star-level on GCOS. - 9 - Get To download (get) a file from GCOS to the microcomputer, enter GET pathname where "pathname" specifies the GCOS file you want to get. The file name at the end of "pathname" will be used as the MS-DOS file name. To give the MS-DOS file a different name, enter GET Kermit-MS will prompt for "Remote Source File: ". You should respond with the pathname of the GCOS file. Kermit-MS will then prompt for "Local Destination File: ". You should respond with the MS-DOS name under which you wish the file to be saved. The remote file may be an index file. If you type get index=/mylist this indicates that the GCOS file "/mylist" contains the names of files to be sent. Logout This command ends your GCOS session for you but does not exit Kermit. Send To upload (send) a file from Kermit-MS to Kermit-GCOS, enter SEND <filespec> [<GCOS filespec> [<option>]*] where "<filespec>" may contain MS-DOS wild-card characters to specify more than one file. For example, SEND *.txt will send all files that have the extension "txt". Since the question mark ("?") is used within Kermit-MS to obtain help, you must use the equal sign ("=") for single-character wild-cards. The <GCOS filespec> may be a list of filenames and index files (see SEND in the commands section). Status This command displays the current status of Kermit-GCOS. This Server mode command is not currently supported by Kermit-MS, so there is no way to invoke it. Type To display the contents of a GCOS file, enter - 10 - REMote TYPE <filename> and the file will be printed, maddenly slowly, on your screen. 1.3.1. Sample Kermit Sessions_____________ You must always begin a Kermit transfer by starting your local Ker- mit and setting local options, then connecting to TSS. The local op- tions available and how to set them will depend on what computer and version of Kermit you are using. However, some options must be set cor- rectly before a connection can be established and before file transfer is possible. These include baud rate, local end of line, and local echo. The following sample session with Kermit-MS and Kermit-GCOS down- loads (gets) a file from GCOS to MS-DOS. The example assumes that drive "A" is your default drive and that it contains a disk with the MSKERMIT program. User input is underlined. The sequence ^]C refers to "control-]" followed by "C", i.e. hold the control key down and press the ] key then release the control key and type a "C". For other ver- sions of microcomputer Kermit, the details will be different. This session transfers the GCOS file "myfile" under subcatalog "my- cat" of your logon userid to the MS-DOS file "dosfile.txt" using a 1200 baud connection to a GCOS system which uses "@" as the character delete symbol. A>_m_s_k_e_r_m_i_t IBM-PC Kermit-MS V2.26 Type ? for help Kermit-MS>_s_e_t_ _b_a_u_d_ _1_2_0_0 Kermit-MS>_s_e_t_ _l_o_c_a_l_-_e_c_h_o_ _o_n Kermit-MS>_s_e_t_ _e_n_d_-_o_f_-_l_i_n_e_ _1_9 Kermit-MS>_c_o_n_n_e_c_t [Connecting to host, type control-] C to return to PC] RETURN______ HIS TIME-SHARING SYSTEM mm/dd/yy hh.mmm CHANNEL xxxx USERID- _u_s_e_r_i_d_$_p_a_s_s_w_o_r_d *_k_e_r_m_i_t_ _s_e_r_v_e_r Kermit-GCOS: Version 1.0 Entering Server Mode. Escape back to your local KERMIT and use server commands. To exit Server Mode, enter the FINISH command from your local KERMIT. To exit KERMIT in an emergency, enter control-D control-S (^D^S) _^_]_C Kermit-MS>_g_e_t Remote Source File: _/_m_y_c_a_t_/_m_y_f_i_l_e - 11 - Local Destination File: _d_o_s_f_i_l_e_._t_x_t <Here follows the file transfer> Kermit-MS>_b_y_e A> The next example shows the same file transfer using version 1.20 of Kermit-PC without server mode. This transfer is to a GCOS system which accepts "@" as character data, so it uses the -TapeMode option. A>_k_e_r_m_i_t CUCCA IBM-PC Kermit-PC Version 1.20 Kermit-PC>_s_e_t_ _b_a_u_d_ _1_2_0_0 Kermit-PC>_s_e_t_ _l_o_c_a_l_ _o_n Kermit-PC>_c_o_n_n_e_c_t [Connecting to host. Type CTRL-]C to return to PC.] _R_E_T_U_R_N HIS TIME-SHARING SYSTEM mm/dd/yy hh.mmm CHANNEL xxxx USERID- _u_s_e_r_i_d_$_p_a_s_s_w_o_r_d *_k_e_r_m_i_t_ _-_t_m Kermit-GCOS: Version 1.0 Kermit-GCOS>_s_e_n_d_ _/_m_y_c_a_t_/_m_y_f_i_l_e Escape back to your local KERMIT and enter RECEIVE mode. _^_]_C Kermit-PC>_r_e_c_e_i_v_e_ _d_o_s_f_i_l_e_._t_x_t <Here follows the file transfer> Kermit-PC>_c_o_n_n_e_c_t _R_E_T_U_R_N *_b_y_e <GCOS logoff summary> _^_]_C Kermit-PC>_e_x_i_t A> Transferring a file from your microcomputer to GCOS is similar, but you would enter a RECEIVE command for Kermit-GCOS (or place it in server mode), then escape back to your local Kermit and enter a send command. - 12 - 1.4.1. Bootstrapping Kermit-GCOS___________ There are three different ways which you may obtain Kermit-GCOS: through the HLSUA library, from Columbia University, or over a telecom- munications line. The easiest is through the HLSUA library as a FILSYS save tape. Installation instructions accompany the tape. The Columbia University CUCCA Kermit distribution tape contains five files for Kermit-GCOS. These are: Name Lines Content HDPS8.B 3489 B language source for Kermit-GCOS HDPS8.DOC 924 This documentation in printable form HDPS8.PAK 1957 Kermit-GCOS H* in packed text format HDPS8.ROF 915 This documentation in ROFF input form HDPS8.FTN 122 Fortran program to convert .PAK file to H* All five files are in text format. The first step in installing Kermit- GCOS is, of course, to copy these files from the tape to disk. Since the Columbia tape cannot contain a Honeywell random binary file, Kermit is provided in packed ASCII text form (HDPS8.PAK) along with a Fortran program (HDPS8.FTN) which documents the packed format and converts the packed file into Honeywell executable (H*) format. Create a 65 block random file to hold the H* and run the following job: $$t(;) $;ident;userid,banner $;option;fortran $;use;.gtlit $;fortran;ascii,xref,optz $$select(userid/hdps8.ftn) $;execute $;prmfl;01,w,r,userid/kermit $;prmfl;02,r,s,userid/hdps8.pak $;endjob After this job runs, copy file "userid/kermit" to "cmdlib/kerm" to make Kermit available through the command library. The packed text file contains a checksum byte on each line, and does not contain and GRTS character delete codes (@), so it can be sent to GCOS over a telecommuncations connection using any ASCII file transfer program. The installation process for generating an H* file is the same as described above. The program will print warning messages if any checksum errors are encountered. - 13 - 1.4.2. Setting Local Options______________ Kermit-GCOS contains three flags to enable setting local options. As distributed, all three flags are set to false. The flags allow setting the default working directory to the current TSS working direc- tory instead of the USERID when entering Kermit, enabling the server command for remote directory, and enabling the server command for remote space information. You should enable remote directory only if you have the LC command which is distributed with the B language package written at the University of Waterloo. You should enable the remote space com- mand only if you have replaced the standard Honeywell SMCL command with a version which permits directing output to a file with "SMCL >filename". You should enable the working directory switch only if your site has enabled the Honeywell TSS working directory feature. Note that Kermit working directories can be used regardless of the setting of this switch-- it controls only the default working directory on entry to Ker- mit. After running HDPS8.FTN to convert the Kermit packed text file into an H*, you can use LODX to modify the flag locations to match local capabilities. The flag addresses are Address (Octal) Content 000153 wat_lc 000154 wat_smcl 000155 wat_cwd All values are initially false (zero). The following example enables remote directory and working directory initialization. *_l_o_d_x_ _/_k_e_r_m_i_t patch, save or run? _p ?_1_5_3_ _1 ?_1_5_5_ _1 ?_<_r_e_t_u_r_n_> patch, save or run? _s patch, save or run?_<_r_e_t_u_r_n_> * These values are declared at the beginning of the EXTRN section of the B source code. You can adjust the settings for your site there if you recompile the source code. Note that the user documentation describes Kermit with the default (false) settings for all three switches. That is, it does not list REMOTE DIRECTORY and REMOTE SPACE as available server commands, and states that the working directory is initially set to the USERID. If you modify these flags, update the documentation. - 14 -